Repository navigation
Add the docs-site troubleshooting page - #145
Merged
Merged
Conversation
The site documented the window's happy paths; the behaviors that look like bugs but are designed (async loading, search index build, refresh deferral while Unity is busy, minimum window and pane sizes, corrupt state recovery) and the capture pipeline's regeneration flow lived only in issues and progress notes. The roadmap's T11 item asked for a troubleshooting page. Refs #114. ## Behavior - docs/troubleshooting.md covers the recorded topics, each traced to main: the Loading... counter and Loading In Progress refusal, Building search index..., busy-database refresh deferral and postprocessor auto-refresh, missing-script and exact-type listing rules, idle-time selection normalization, 860x480 / pane minimums with preferred-vs-clamped sizes, user-state and settings-asset recovery, and capture regeneration (CLI, output-dir argument and env var, project-root path resolution, meta-free dot-folder staging, the macOS 6000.4 render-gap limit, container workflow). - mkdocs.yml nav gains Troubleshooting after Extending; the index page links it in Where to go next. ## Validation - mkdocs build --strict green; site/troubleshooting/ published with all ten sections, the five PNGs present, and zero .meta files. - npm run lint:llm green; npm pack payload unchanged (172 files).
This was referenced Oct 9, 2026
wallstop
added a commit
that referenced
this pull request
Oct 12, 2026
The T11 roadmap still listed the troubleshooting page and the Odin behavior documentation as open even though both are on main: the troubleshooting page shipped in #145 and the extending guide's Odin Inspector section documents the behavior separately from the default inspector contract since #134. Checking both boxes keeps the roadmap truthful about what is delivered and leaves the measured-performance section as the only open T11 item (issue #114, still T01-blocked). Why: stale unchecked boxes misstate the package's documentation state to every agent and contributor planning work from the roadmap.
wallstop
added a commit
that referenced
this pull request
Oct 12, 2026
DISCLOSURE: LLM-GENERATED TEXT **Why:** the T11 roadmap still listed delivered documentation as open, misstating the docs state to every planner. **What:** - Check the troubleshooting-page box, delivered in #145 - Check the Odin-docs box, delivered with the extending guide in #134 - The measured-performance section stays the one open T11 item Refs #114, #145 <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Low Risk** > Roadmap checkbox edits only; no runtime, build, or publication behavior changes. > > **Overview** > Updates **T11** in `.llm/references/roadmap.md` so the plan matches what is already on the default branch: the **troubleshooting** item is marked done with ref **#145**, and **Odin vs default inspector** is marked done with **docs/extending.md** / **#134**. > > The only remaining open T11 checkbox is the **measured performance** section, still blocked on T01 numbers. No product code or site content changes—only roadmap status accuracy for planners. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit ba36af5. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup> <!-- /CURSOR_SUMMARY -->
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The site documented the happy paths; the behaviors that look like bugs but are designed lived only in issues and progress notes. The T11 roadmap item asked for a troubleshooting page. Refs #114.
Behavior
docs/troubleshooting.md: async loading and theLoading In Progressrefusal,Building search index…, busy-database refresh deferral and postprocessor auto-refresh, missing-script and exact-type listing rules, idle-time selection normalization, the 860x480 and per-pane minimums with preferred-vs-clamped sizes, user-state and settings-asset recovery, and capture regeneration (CLI, output-dir argument/env var, project-root path resolution, meta-free staging, the macOS 6000.4 render-gap limit, container workflow). Every claim traced tomain.mkdocs.ymlnav gains Troubleshooting after Extending; the index links it under Where to go next.Validation
mkdocs build --strictgreen;site/troubleshooting/published with all ten sections, the five PNGs present, zero.metafiles; cross-page links resolve.npm run lint:llmgreen;npm packpayload unchanged (172 files, nodocs/paths). Docs-only change: Unity suites not exercised (precedent Add the documentation site foundation (T11) #130, Document search, filtering, asset operations, and extension points #134, Publish the capture-pipeline imagery on the docs site #144).Risk / Rollback
Note
Low Risk
Documentation-only; no runtime or package code changes. Risk is outdated or incorrect user guidance, including capture-limit wording tied to #114.
Overview
Adds a Troubleshooting page to the MkDocs site (
docs/troubleshooting.md) so “looks broken but is by design” behavior is documented in one place instead of issues/notes. Sections cover gradual async object loading and processor refusal while loading, first-search index build, deferred refresh when the AssetDatabase is busy or Play Mode is active, exact-type and missing-script listing rules, post-recompile selection cleanup, window/pane minimum sizes, corrupt or empty persistence recovery, and how to regeneratedocs/images/viaDocsImageCapture(CLI, env var, staging paths, validation, and the macOS 6000.4 capture gap tied to #114), plus a short container/host edit workflow note.Navigation:
mkdocs.ymland Where to go next indocs/index.mdlink the new page. The diff currently registers Troubleshooting twice in both places (two nav items and two index bullets with slightly different blurbs)—likely an accidental duplicate worth collapsing to a single entry. A Unity.metacompanion for the markdown file is also added.Reviewed by Cursor Bugbot for commit 3be6036. Bugbot is set up for automated code reviews on this repo. Configure here.